<!DOCTYPE html>
<html class="writer-html4" lang="en" >
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Advanced Usage &mdash; P4-Utils 1.0 documentation</title><link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
  <!--[if lt IE 9]>
    <script src="_static/js/html5shiv.min.js"></script>
  <![endif]-->
  
      <script>
          var DOCUMENTATION_OPTIONS = {
              URL_ROOT:'./',
              VERSION:'1.0',
              LANGUAGE:'None',
              COLLAPSE_INDEX:false,
              FILE_SUFFIX:'.html',
              HAS_SOURCE:  false,
              SOURCELINK_SUFFIX: '.txt'
          };
      </script>
        <script src="_static/jquery.js"></script>
        <script src="_static/underscore.js"></script>
        <script src="_static/doctools.js"></script>
        <script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
    <script src="_static/js/theme.js"></script>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="P4-Utils API reference" href="p4utils.html" />
    <link rel="prev" title="Usage" href="usage.html" /> 
</head>

<body class="wy-body-for-nav"> 
  <div class="wy-grid-for-nav">
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search" >
            <a href="index.html" class="icon icon-home"> P4-Utils
          </a>
              <div class="version">
                1.0
              </div>
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>
        </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
              <p class="caption"><span class="caption-text">General Documentation</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="introduction.html">Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="installation.html">Installation</a></li>
<li class="toctree-l1"><a class="reference internal" href="usage.html">Usage</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Advanced Usage</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#control-plane-configuration">Control Plane Configuration</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#thrift-api">Thrift API</a></li>
<li class="toctree-l3"><a class="reference internal" href="#p4runtime-api">P4Runtime API</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#enabling-p4runtime-with-python">Enabling P4Runtime with Python</a></li>
<li class="toctree-l4"><a class="reference internal" href="#enabling-p4runtime-with-json">Enabling P4Runtime with JSON</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#topology-database">Topology Database</a></li>
<li class="toctree-l2"><a class="reference internal" href="#task-scheduler">Task Scheduler</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#scheduling-tasks-with-the-network-client">Scheduling tasks with the Network Client</a></li>
<li class="toctree-l3"><a class="reference internal" href="#scheduling-tasks-with-a-file">Scheduling tasks with a file</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<p class="caption"><span class="caption-text">API Reference</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="p4utils.html">P4-Utils API reference</a></li>
</ul>

        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="index.html">P4-Utils</a>
      </nav>

      <div class="wy-nav-content">
        <div class="rst-content">
          <div role="navigation" aria-label="Page navigation">
  <ul class="wy-breadcrumbs">
      <li><a href="index.html" class="icon icon-home"></a> &raquo;</li>
      <li>Advanced Usage</li>
      <li class="wy-breadcrumbs-aside">
              <a href="https://github.com/nsg-ethz/p4-utils/blob/master/docs/source/advanced_usage.rst" class="fa fa-github"> Edit on GitHub</a>
      </li>
  </ul>
  <hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
             
  <div class="section" id="advanced-usage">
<h1>Advanced Usage<a class="headerlink" href="#advanced-usage" title="Permalink to this headline">¶</a></h1>
<p>In this page we give an overview of the most advanced features available in P4-Utils. In the
following paragraphs, we will explore some programmatic ways to control the switch
and to schedule tasks on the nodes of the network.</p>
<p>To get started, let us consider again the example already presented in the <a class="reference external" href="usage.html">usage section</a>.
Let us assume, that we already followed the instructions to create the network and we are
now able to start it. We need to configure the switch <code class="docutils literal"><span class="pre">s1</span></code> to make it able to perform
L2 forwarding.</p>
<img alt="_images/l2_topology.png" class="align-center" src="_images/l2_topology.png" />
<div class="admonition important">
<p class="first admonition-title">Important</p>
<p class="last">For more examples and use cases, we recommend to check out the repository <a class="reference external" href="https://github.com/nsg-ethz/p4-learning">P4-Learning</a>. It
is a collections of working examples and exercises that are very helpful to start programming
with P4.</p>
</div>
<div class="section" id="control-plane-configuration">
<h2>Control Plane Configuration<a class="headerlink" href="#control-plane-configuration" title="Permalink to this headline">¶</a></h2>
<p>In the following sections, we explore two alternatives to the <em>Thrift</em> command-line
client <a class="reference external" href="usage.html#thrift-client">method</a> to control the switch.</p>
<div class="section" id="thrift-api">
<h3>Thrift API<a class="headerlink" href="#thrift-api" title="Permalink to this headline">¶</a></h3>
<p>The <em>Thrift API</em> can be used with every P4 switch and it is based on the code of the
<em>Thrift</em> command-line client. In fact, it provides the same methods to control the switch.
The implementation of the <em>Thrift API</em> relies on
<a class="reference internal" href="p4utils.utils.sswitch_thrift_API.html#p4utils.utils.sswitch_thrift_API.SimpleSwitchThriftAPI" title="p4utils.utils.sswitch_thrift_API.SimpleSwitchThriftAPI"><code class="xref py py-class docutils literal"><span class="pre">SimpleSwitchThriftAPI</span></code></a>.</p>
<p>To get started, we create a new Python script called <code class="docutils literal"><span class="pre">controller.py</span></code> and we import
the module needed to configure the P4 switch:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">p4utils.utils.sswitch_thrift_API</span> <span class="kn">import</span> <span class="n">SimpleSwitchThriftAPI</span>
</pre></div>
</div>
<p>We also need to esablish a connection with the server running on the switch. We know
that the <em>Thrift</em> server of <code class="docutils literal"><span class="pre">s1</span></code> is listening on <code class="docutils literal"><span class="pre">127.0.0.1:9090</span></code> (see <a class="reference external" href="usage.html#thrift-client">here</a>), so we can
connect using:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">controller</span> <span class="o">=</span> <span class="n">SimpleSwitchThriftAPI</span><span class="p">(</span><span class="mi">9090</span><span class="p">)</span>
</pre></div>
</div>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last"><a class="reference internal" href="p4utils.utils.sswitch_thrift_API.html#p4utils.utils.sswitch_thrift_API.SimpleSwitchThriftAPI" title="p4utils.utils.sswitch_thrift_API.SimpleSwitchThriftAPI"><code class="xref py py-class docutils literal"><span class="pre">SimpleSwitchThriftAPI</span></code></a> assumes by default
that the IP address of the <em>Thrift</em> server is <code class="docutils literal"><span class="pre">127.0.0.1</span></code>.</p>
</div>
<p>Now, we can use the controller to set up our forwarding rules. We can use the
method <a class="reference internal" href="p4utils.utils.thrift_API.html#p4utils.utils.thrift_API.ThriftAPI.table_add" title="p4utils.utils.thrift_API.ThriftAPI.table_add"><code class="xref py py-meth docutils literal"><span class="pre">table_add()</span></code></a>:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">controller</span><span class="o">.</span><span class="n">table_add</span><span class="p">(</span><span class="s1">&#39;dmac&#39;</span><span class="p">,</span> <span class="s1">&#39;forward&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;00:00:0a:00:00:01&#39;</span><span class="p">],</span> <span class="p">[</span><span class="s1">&#39;1&#39;</span><span class="p">])</span>
<span class="n">controller</span><span class="o">.</span><span class="n">table_add</span><span class="p">(</span><span class="s1">&#39;dmac&#39;</span><span class="p">,</span> <span class="s1">&#39;forward&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;00:00:0a:00:00:02&#39;</span><span class="p">],</span> <span class="p">[</span><span class="s1">&#39;2&#39;</span><span class="p">])</span>
<span class="n">controller</span><span class="o">.</span><span class="n">table_add</span><span class="p">(</span><span class="s1">&#39;dmac&#39;</span><span class="p">,</span> <span class="s1">&#39;forward&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;00:00:0a:00:00:03&#39;</span><span class="p">],</span> <span class="p">[</span><span class="s1">&#39;3&#39;</span><span class="p">])</span>
<span class="n">controller</span><span class="o">.</span><span class="n">table_add</span><span class="p">(</span><span class="s1">&#39;dmac&#39;</span><span class="p">,</span> <span class="s1">&#39;forward&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;00:00:0a:00:00:04&#39;</span><span class="p">],</span> <span class="p">[</span><span class="s1">&#39;4&#39;</span><span class="p">])</span>
</pre></div>
</div>
<p>Now, after the network starts, we can run the controller script to populate the
forwarding table of <code class="docutils literal"><span class="pre">s1</span></code>:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">python3</span> <span class="n">controller</span><span class="o">.</span><span class="n">py</span>
</pre></div>
</div>
<div class="admonition important">
<p class="first admonition-title">Important</p>
<p class="last">This guide is just a quick overview of how to use the <em>Thrift API</em>. Please check
out the documentation of <a class="reference internal" href="p4utils.utils.sswitch_thrift_API.html#p4utils.utils.sswitch_thrift_API.SimpleSwitchThriftAPI" title="p4utils.utils.sswitch_thrift_API.SimpleSwitchThriftAPI"><code class="xref py py-class docutils literal"><span class="pre">SimpleSwitchThriftAPI</span></code></a>
and <a class="reference internal" href="p4utils.utils.thrift_API.html#p4utils.utils.thrift_API.ThriftAPI" title="p4utils.utils.thrift_API.ThriftAPI"><code class="xref py py-class docutils literal"><span class="pre">ThriftAPI</span></code></a> to learn more advanced options.</p>
</div>
</div>
<div class="section" id="p4runtime-api">
<h3>P4Runtime API<a class="headerlink" href="#p4runtime-api" title="Permalink to this headline">¶</a></h3>
<p>The <em>P4Runtime API</em> is implemented by
<a class="reference internal" href="p4utils.utils.sswitch_p4runtime_API.html#p4utils.utils.sswitch_p4runtime_API.SimpleSwitchP4RuntimeAPI" title="p4utils.utils.sswitch_p4runtime_API.SimpleSwitchP4RuntimeAPI"><code class="xref py py-class docutils literal"><span class="pre">SimpleSwitchP4RuntimeAPI</span></code></a> and can
only be used with P4Runtime capable switches: not all the binaries provided by the
<a class="reference external" href="https://github.com/p4lang/behavioral-model">behavioral-model</a> implement this feature. As a consequence, only
<a class="reference internal" href="p4utils.mininetlib.node.html#p4utils.mininetlib.node.P4RuntimeSwitch" title="p4utils.mininetlib.node.P4RuntimeSwitch"><code class="xref py py-class docutils literal"><span class="pre">P4RuntimeSwitch</span></code></a> supports P4Runtime, whereas
<a class="reference internal" href="p4utils.mininetlib.node.html#p4utils.mininetlib.node.P4Switch" title="p4utils.mininetlib.node.P4Switch"><code class="xref py py-class docutils literal"><span class="pre">P4Switch</span></code></a> does not.</p>
<p>For this reason, we provide a quick guide on how to enable P4Runtime in your network using the
<a class="reference external" href="#enabling-p4runtime-with-python">Python script</a> or the <a class="reference external" href="#enabling-p4runtime-with-json">JSON file</a>.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">The <a class="reference external" href="https://github.com/p4lang/behavioral-model">behavioral-model</a> must be build with the P4Runtime dependencies in order to
make it work. Otherwise, only non-P4Runtime targets will be available.</p>
</div>
<p>Assuming that we have correctly enabled P4Runtime, we can write our Python P4Runtime
controller (called <code class="docutils literal"><span class="pre">controller.py</span></code>) for the switch <code class="docutils literal"><span class="pre">s1</span></code>:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">p4utils.utils.sswitch_p4runtime_API</span> <span class="kn">import</span> <span class="n">SimpleSwitchP4RuntimeAPI</span>

<span class="n">controller</span> <span class="o">=</span> <span class="n">SimpleSwitchP4RuntimeAPI</span><span class="p">(</span><span class="n">device_id</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">grpc_port</span><span class="o">=</span><span class="mi">9559</span><span class="p">,</span>
                                      <span class="n">p4rt_path</span><span class="o">=</span><span class="s1">&#39;l2_forwarding_p4rt.txt&#39;</span><span class="p">,</span>
                                      <span class="n">json_path</span><span class="o">=</span><span class="s1">&#39;l2_forwarding.json&#39;</span><span class="p">)</span>
</pre></div>
</div>
<div class="admonition important">
<p class="first admonition-title">Important</p>
<p class="last">Both the P4Info file <code class="docutils literal"><span class="pre">l2_forwarding_p4rt.txt</span></code> and the P4 compiled JSON file
<code class="docutils literal"><span class="pre">l2_forwarding.json</span></code> are generated by the P4 compiler. In order to enable the P4Info file
generation, please check the P4Runtime guides for <a class="reference external" href="#enabling-p4runtime-with-python">Python</a> and <a class="reference external" href="#enabling-p4runtime-with-json">JSON</a>.</p>
</div>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<ul class="last simple">
<li>The <code class="docutils literal"><span class="pre">device_id</span></code> can be explicitly assigned to the switches in the network configuration.
If the <code class="docutils literal"><span class="pre">device_id</span></code> is not specified for any switch in the network, then the alphabetic
order is used for the assignment and the first switch will get <code class="docutils literal"><span class="pre">1</span></code>.</li>
<li>The <code class="docutils literal"><span class="pre">grpc_port</span></code> can be explicitly assigned to the P4Runtime switches in the
network configuration. If the <code class="docutils literal"><span class="pre">grpc_port</span></code> is not specified for any P4Runtime switch in
the network, then the alphabetic order is used for the assignment and the first P4Runtime
switch will get <code class="docutils literal"><span class="pre">9559</span></code>.</li>
</ul>
</div>
<p>Now, we can use the controller to set up our forwarding rules. We can use the
method <a class="reference internal" href="p4utils.utils.sswitch_p4runtime_API.html#p4utils.utils.sswitch_p4runtime_API.SimpleSwitchP4RuntimeAPI.table_add" title="p4utils.utils.sswitch_p4runtime_API.SimpleSwitchP4RuntimeAPI.table_add"><code class="xref py py-meth docutils literal"><span class="pre">table_add()</span></code></a>:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">controller</span><span class="o">.</span><span class="n">table_add</span><span class="p">(</span><span class="s1">&#39;dmac&#39;</span><span class="p">,</span> <span class="s1">&#39;forward&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;00:00:0a:00:00:01&#39;</span><span class="p">],</span> <span class="p">[</span><span class="s1">&#39;1&#39;</span><span class="p">])</span>
<span class="n">controller</span><span class="o">.</span><span class="n">table_add</span><span class="p">(</span><span class="s1">&#39;dmac&#39;</span><span class="p">,</span> <span class="s1">&#39;forward&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;00:00:0a:00:00:02&#39;</span><span class="p">],</span> <span class="p">[</span><span class="s1">&#39;2&#39;</span><span class="p">])</span>
<span class="n">controller</span><span class="o">.</span><span class="n">table_add</span><span class="p">(</span><span class="s1">&#39;dmac&#39;</span><span class="p">,</span> <span class="s1">&#39;forward&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;00:00:0a:00:00:03&#39;</span><span class="p">],</span> <span class="p">[</span><span class="s1">&#39;3&#39;</span><span class="p">])</span>
<span class="n">controller</span><span class="o">.</span><span class="n">table_add</span><span class="p">(</span><span class="s1">&#39;dmac&#39;</span><span class="p">,</span> <span class="s1">&#39;forward&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;00:00:0a:00:00:04&#39;</span><span class="p">],</span> <span class="p">[</span><span class="s1">&#39;4&#39;</span><span class="p">])</span>
</pre></div>
</div>
<p>Now, after the network starts, we can run the controller script to populate the
forwarding table of <code class="docutils literal"><span class="pre">s1</span></code>:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">python3</span> <span class="n">controller</span><span class="o">.</span><span class="n">py</span>
</pre></div>
</div>
<div class="admonition important">
<p class="first admonition-title">Important</p>
<p class="last">This example is only a brief overview of the most common options available with
the <em>P4Runtime API</em>. Please check out the documentation of
<a class="reference internal" href="p4utils.utils.sswitch_p4runtime_API.html#p4utils.utils.sswitch_p4runtime_API.SimpleSwitchP4RuntimeAPI" title="p4utils.utils.sswitch_p4runtime_API.SimpleSwitchP4RuntimeAPI"><code class="xref py py-class docutils literal"><span class="pre">SimpleSwitchP4RuntimeAPI</span></code></a>
to learn more advanced methods.</p>
</div>
<div class="section" id="enabling-p4runtime-with-python">
<h4>Enabling P4Runtime with Python<a class="headerlink" href="#enabling-p4runtime-with-python" title="Permalink to this headline">¶</a></h4>
<p>Considering our simple example, the P4 compiler has to know that we are using a P4Runtime switch
to generate the P4Info file needed to connect to the P4Runtime server of the switch.</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">net</span><span class="o">.</span><span class="n">setCompiler</span><span class="p">(</span><span class="n">p4rt</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
</pre></div>
</div>
<p>Afterwards, we need also to specify that we are using P4Runtime switches. In the
Python network configuration script, this can be done by writing:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">net</span><span class="o">.</span><span class="n">addP4RuntimeSwtich</span><span class="p">(</span><span class="s1">&#39;s1&#39;</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="enabling-p4runtime-with-json">
<h4>Enabling P4Runtime with JSON<a class="headerlink" href="#enabling-p4runtime-with-json" title="Permalink to this headline">¶</a></h4>
<p>For what concerns the JSON confinguration files, the P4 compiler can generate the P4Info if
one specifies it with the <code class="docutils literal"><span class="pre">compiler_module</span></code> option. Moreover, one can set the default
type of P4 switches with the <code class="docutils literal"><span class="pre">switch_node</span></code> option. In this way, we can make every switch a
<a class="reference internal" href="p4utils.mininetlib.node.html#p4utils.mininetlib.node.P4RuntimeSwitch" title="p4utils.mininetlib.node.P4RuntimeSwitch"><code class="xref py py-class docutils literal"><span class="pre">P4RuntimeSwitch</span></code></a>.</p>
<p>After having applied all the aforementioned settings to the JSON network configuration file of
our simple example, it looks like this:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="p">{</span>
  <span class="s2">&quot;p4_src&quot;</span><span class="p">:</span> <span class="s2">&quot;l2_forwarding.p4&quot;</span><span class="p">,</span>
  <span class="s2">&quot;cli&quot;</span><span class="p">:</span> <span class="n">true</span><span class="p">,</span>
  <span class="s2">&quot;pcap_dump&quot;</span><span class="p">:</span> <span class="n">true</span><span class="p">,</span>
  <span class="s2">&quot;enable_log&quot;</span><span class="p">:</span> <span class="n">true</span><span class="p">,</span>
  <span class="s2">&quot;compiler_module&quot;</span><span class="p">:</span>
  <span class="p">{</span>
    <span class="s2">&quot;options&quot;</span><span class="p">:</span>
    <span class="p">{</span>
      <span class="s2">&quot;p4rt&quot;</span><span class="p">:</span> <span class="n">true</span>
    <span class="p">}</span>
  <span class="p">},</span>
  <span class="s2">&quot;switch_node&quot;</span><span class="p">:</span>
  <span class="p">{</span>
    <span class="s2">&quot;module_name&quot;</span><span class="p">:</span> <span class="s2">&quot;p4utils.mininetlib.node&quot;</span><span class="p">,</span>
    <span class="s2">&quot;object_name&quot;</span><span class="p">:</span> <span class="s2">&quot;P4RuntimeSwitch&quot;</span>
  <span class="p">},</span>
  <span class="s2">&quot;topology&quot;</span><span class="p">:</span> <span class="p">{</span>
    <span class="s2">&quot;assignment_strategy&quot;</span><span class="p">:</span> <span class="s2">&quot;l2&quot;</span><span class="p">,</span>
    <span class="s2">&quot;default&quot;</span><span class="p">:</span> <span class="p">{</span>
      <span class="s2">&quot;bw&quot;</span><span class="p">:</span> <span class="mi">10</span>
    <span class="p">},</span>
    <span class="s2">&quot;links&quot;</span><span class="p">:</span> <span class="p">[[</span><span class="s2">&quot;h1&quot;</span><span class="p">,</span> <span class="s2">&quot;s1&quot;</span><span class="p">],</span> <span class="p">[</span><span class="s2">&quot;h2&quot;</span><span class="p">,</span> <span class="s2">&quot;s1&quot;</span><span class="p">],</span> <span class="p">[</span><span class="s2">&quot;h3&quot;</span><span class="p">,</span> <span class="s2">&quot;s1&quot;</span><span class="p">],</span> <span class="p">[</span><span class="s2">&quot;h4&quot;</span><span class="p">,</span> <span class="s2">&quot;s1&quot;</span><span class="p">]],</span>
    <span class="s2">&quot;hosts&quot;</span><span class="p">:</span> <span class="p">{</span>
      <span class="s2">&quot;h1&quot;</span><span class="p">:</span> <span class="p">{</span>
      <span class="p">},</span>
      <span class="s2">&quot;h2&quot;</span><span class="p">:</span> <span class="p">{</span>
      <span class="p">}</span>
      <span class="p">,</span>
      <span class="s2">&quot;h3&quot;</span><span class="p">:</span> <span class="p">{</span>
      <span class="p">}</span>
      <span class="p">,</span>
      <span class="s2">&quot;h4&quot;</span><span class="p">:</span> <span class="p">{</span>
      <span class="p">}</span>
    <span class="p">},</span>
    <span class="s2">&quot;switches&quot;</span><span class="p">:</span> <span class="p">{</span>
      <span class="s2">&quot;s1&quot;</span><span class="p">:</span> <span class="p">{</span>
      <span class="p">}</span>
    <span class="p">}</span>
  <span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
</div>
</div>
<div class="section" id="topology-database">
<h2>Topology Database<a class="headerlink" href="#topology-database" title="Permalink to this headline">¶</a></h2>
<p>Until now we have seen different methods to control the switch, but they always rely on the
information that the user provides: the user has to know all the network addresses, the port
numbers, etc. Although this is feasible with small topologies, it becomes harder with large ones,
where you have to deal with tens or even hundreds of addresses and port numbers.</p>
<p>In order to overcome this issue, P4-Utils has a built-in topology database that is automatically
generated after the network starts and it is saved to a JSON file, usually called <code class="docutils literal"><span class="pre">topology.json</span></code>,
in the execution directory. One can then query this file to retrieve topology information.
This framework is implemented by <a class="reference internal" href="p4utils.utils.topology.html#p4utils.utils.topology.NetworkGraph" title="p4utils.utils.topology.NetworkGraph"><code class="xref py py-class docutils literal"><span class="pre">NetworkGraph</span></code></a>.</p>
<p>For example, let us consider our simple example. We can automatically configure the forwarding
table without knowing anything about the switch:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">p4utils.utils.helper</span> <span class="kn">import</span> <span class="n">load_topo</span>
<span class="kn">from</span> <span class="nn">p4utils.utils.sswitch_p4runtime_API</span> <span class="kn">import</span> <span class="n">SimpleSwitchP4RuntimeAPI</span>

<span class="n">topo</span> <span class="o">=</span> <span class="n">load_topo</span><span class="p">(</span><span class="s1">&#39;topology.json&#39;</span><span class="p">)</span>

<span class="n">controller</span> <span class="o">=</span> <span class="n">SimpleSwitchP4RuntimeAPI</span><span class="p">(</span><span class="n">topo</span><span class="p">[</span><span class="s1">&#39;s1&#39;</span><span class="p">][</span><span class="s1">&#39;device_id&#39;</span><span class="p">],</span>
                                       <span class="n">topo</span><span class="p">[</span><span class="s1">&#39;s1&#39;</span><span class="p">][</span><span class="s1">&#39;grpc_port&#39;</span><span class="p">],</span>
                                       <span class="n">p4rt_path</span><span class="o">=</span><span class="n">topo</span><span class="p">[</span><span class="s1">&#39;s1&#39;</span><span class="p">][</span><span class="s1">&#39;p4rt_path&#39;</span><span class="p">],</span>
                                       <span class="n">json_path</span><span class="o">=</span><span class="n">topo</span><span class="p">[</span><span class="s1">&#39;s1&#39;</span><span class="p">][</span><span class="s1">&#39;json_path&#39;</span><span class="p">])</span>

<span class="k">for</span> <span class="n">neigh</span> <span class="n">topo</span><span class="o">.</span><span class="n">get_neighbors</span><span class="p">(</span><span class="s1">&#39;s1&#39;</span><span class="p">):</span>
    <span class="k">if</span> <span class="n">topo</span><span class="o">.</span><span class="n">isHost</span><span class="p">(</span><span class="n">neigh</span><span class="p">):</span>
        <span class="n">controller</span><span class="o">.</span><span class="n">table_add</span><span class="p">(</span><span class="s1">&#39;dmac&#39;</span><span class="p">,</span>
                             <span class="s1">&#39;forward&#39;</span><span class="p">,</span>
                             <span class="p">[</span><span class="n">topo</span><span class="o">.</span><span class="n">get_host_mac</span><span class="p">(</span><span class="n">neigh</span><span class="p">)],</span>
                             <span class="p">[</span><span class="nb">str</span><span class="p">(</span><span class="n">topo</span><span class="o">.</span><span class="n">node_to_node_port_num</span><span class="p">(</span><span class="s1">&#39;s1&#39;</span><span class="p">,</span> <span class="n">neigh</span><span class="p">))])</span>
</pre></div>
</div>
<div class="admonition important">
<p class="first admonition-title">Important</p>
<p class="last">This guide is just a basic overview of how to use the topology database. Please check
out the documentation of <a class="reference internal" href="p4utils.utils.topology.html#p4utils.utils.topology.NetworkGraph" title="p4utils.utils.topology.NetworkGraph"><code class="xref py py-class docutils literal"><span class="pre">NetworkGraph</span></code></a> to
learn more advanced techniques involving also routers.</p>
</div>
</div>
<div class="section" id="task-scheduler">
<h2>Task Scheduler<a class="headerlink" href="#task-scheduler" title="Permalink to this headline">¶</a></h2>
<p>The Task Scheduler allows the user to simply schedule different tasks (e.g. generation of traffic)
on different nodes. It can be accessed in two ways:</p>
<ul class="simple">
<li>one can add tasks from the <a class="reference external" href="usage.html#network-client">network client</a>,</li>
<li>one can put the tasks in a <code class="docutils literal"><span class="pre">.txt</span></code> file (one per line) that
is parsed by P4-Utils.</li>
</ul>
<p>Here we provide only simple examples. To learn more about the capabilities of the task scheduler,
you can check out the <a class="reference external" href="https://github.com/nsg-ethz/p4-utils/tree/master/examples">examples</a> of the P4-Utils repository.</p>
<div class="section" id="scheduling-tasks-with-the-network-client">
<h3>Scheduling tasks with the Network Client<a class="headerlink" href="#scheduling-tasks-with-the-network-client" title="Permalink to this headline">¶</a></h3>
<p>After the network starts, we can use the following command in the network client:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">mininet</span><span class="o">&gt;</span> <span class="n">task</span> <span class="o">&lt;</span><span class="n">node</span><span class="o">&gt;</span> <span class="o">&lt;</span><span class="n">start</span><span class="o">&gt;</span> <span class="o">&lt;</span><span class="n">duration</span><span class="o">&gt;</span> <span class="o">&lt;</span><span class="n">exe</span><span class="o">&gt;</span> <span class="p">[</span><span class="o">&lt;</span><span class="n">arg1</span><span class="o">&gt;</span><span class="p">]</span> <span class="o">...</span> <span class="p">[</span><span class="o">&lt;</span><span class="n">argN</span><span class="o">&gt;</span><span class="p">]</span> <span class="p">[</span><span class="o">--</span><span class="n">mod</span> <span class="o">&lt;</span><span class="n">module</span><span class="o">&gt;</span><span class="p">]</span> <span class="p">[</span><span class="o">--&lt;</span><span class="n">key1</span><span class="o">&gt;</span> <span class="o">&lt;</span><span class="n">kwarg1</span><span class="o">&gt;</span><span class="p">]</span> <span class="o">...</span> <span class="p">[</span><span class="o">--&lt;</span><span class="n">keyM</span><span class="o">&gt;</span> <span class="o">&lt;</span><span class="n">kwargM</span><span class="o">&gt;</span><span class="p">]</span>
</pre></div>
</div>
<p>In particular, we have:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">node</span></code> is the node name,</li>
<li><code class="docutils literal"><span class="pre">exe</span></code> is the executable to run (either a shell string command or the name of a Python function),</li>
<li><code class="docutils literal"><span class="pre">argX</span></code> is a positional arguments for the passed function (optional),</li>
<li><code class="docutils literal"><span class="pre">start</span></code> is the task delay in seconds with respect to the current time,</li>
<li><code class="docutils literal"><span class="pre">duration</span></code> is the task duration time in seconds (if duration is lower than or equal to
<code class="docutils literal"><span class="pre">0</span></code>, then the task has no time limitation),</li>
<li><code class="docutils literal"><span class="pre">keyX</span></code> and <code class="docutils literal"><span class="pre">kwargX</span></code> is a key-word arguments for the passed function (optional).</li>
</ul>
<div class="admonition important">
<p class="first admonition-title">Important</p>
<p class="last">The deafult module in which functions are looked up is <a class="reference internal" href="p4utils.utils.traffic_utils.html#module-p4utils.utils.traffic_utils" title="p4utils.utils.traffic_utils"><code class="xref py py-mod docutils literal"><span class="pre">p4utils.utils.traffic_utils</span></code></a>.
A different module can be specified in the command with <code class="docutils literal"><span class="pre">--mod</span> <span class="pre">&lt;module&gt;</span></code>.</p>
</div>
<p>If we consider our simple example, to make <code class="docutils literal"><span class="pre">h1</span></code> ping <code class="docutils literal"><span class="pre">h2</span></code> for 10 seconds, we can type the
the following line in the client:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">mininet</span><span class="o">&gt;</span> <span class="n">task</span> <span class="n">h1</span> <span class="mi">0</span> <span class="mi">10</span> <span class="s2">&quot;ping 10.0.0.2&quot;</span>
</pre></div>
</div>
</div>
<div class="section" id="scheduling-tasks-with-a-file">
<h3>Scheduling tasks with a file<a class="headerlink" href="#scheduling-tasks-with-a-file" title="Permalink to this headline">¶</a></h3>
<p>When dealing with multiple tasks, it is handy to use a single file that collects them all instead
of using the client. This file is parsed during the network boot and the tasks are distributed
right after.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">For task files, the <code class="docutils literal"><span class="pre">start</span></code> value is the delay with respect to the network starting time.</p>
</div>
<p>The syntax of this file is the same of the network client with only one
difference: <strong>you must not put the</strong> <code class="docutils literal"><span class="pre">task</span></code> <strong>command at the beginning of the task line</strong>. You also
have to put one task per line.</p>
<p>For example, let us consider the L2 forwarding example. We want the following tasks:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">h1</span></code> pings <code class="docutils literal"><span class="pre">h2</span></code> for 10 seconds starting 30 seconds after the network boot.</li>
<li><code class="docutils literal"><span class="pre">h3</span></code> pings <code class="docutils literal"><span class="pre">h4</span></code> for 30 seconds starting 10 seconds after the network boot.</li>
</ul>
<p>We can write our file <code class="docutils literal"><span class="pre">tasks.txt</span></code> as follows:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">h1</span> <span class="mi">30</span> <span class="mi">10</span> <span class="s2">&quot;ping 10.0.0.2&quot;</span>
<span class="n">h3</span> <span class="mi">10</span> <span class="mi">30</span> <span class="s2">&quot;ping 10.0.0.4&quot;</span>
</pre></div>
</div>
<p>Now, we need to pass the file to the P4-Utils framework. If you are using a Python network
configuration script, you can add it using the following line:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">net</span><span class="o">.</span><span class="n">addTaskFile</span><span class="p">(</span><span class="s1">&#39;tasks.txt&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>On the other hand, if you are using the JSON configuration file, you can add the following
key-value to the main dictionary (for example, you can place it after the <code class="docutils literal"><span class="pre">p4_src</span></code> option):</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="s2">&quot;tasks_file&quot;</span><span class="p">:</span> <span class="s2">&quot;tasks.txt&quot;</span>
</pre></div>
</div>
<p>Now, you are ready. After the network starts, every task is automatically scheduled
according to the information contained in the tasks file.</p>
</div>
</div>
</div>


           </div>
          </div>
          <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
        <a href="usage.html" class="btn btn-neutral float-left" title="Usage" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
        <a href="p4utils.html" class="btn btn-neutral float-right" title="P4-Utils API reference" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
    </div>

  <hr/>

  <div role="contentinfo">
    <p>&#169; Copyright 2021, Networked Systems Group (NSG@ETH).</p>
  </div>

  Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
    <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
    provided by <a href="https://readthedocs.org">Read the Docs</a>.
   

</footer>
        </div>
      </div>
    </section>
  </div>
  <script>
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
      });
  </script> 

</body>
</html>